home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacOS 8 Resources / Developer Tools / Mac OS 8 Interfaces & Libraries / Interfaces / IDLIncludes / Power.idl < prev    next >
Text File  |  1996-05-01  |  13KB  |  375 lines
  1. /*
  2.      File:        Power.idl
  3.  
  4.      Contains:    Power Manager Interfaces.
  5.  
  6.      Version:    Technology:    System 7.5
  7.                  Release:    Universal Interfaces 3.0d3 on Copland DR1
  8.  
  9.      Copyright:    © 1984-1996 by Apple Computer, Inc.  All rights reserved.
  10.  
  11.      Bugs?:        If you find a problem with this file, send the file and version
  12.                  information (from above) and the problem description to:
  13.  
  14.                      Internet:    apple.bugs@applelink.apple.com
  15.                      AppleLink:    APPLE.BUGS
  16.  
  17. */
  18. #ifndef __POWER_IDL__
  19. #define __POWER_IDL__
  20.  
  21. #include <somobj.idl>
  22. #include <somcls.idl>
  23.  
  24. #ifndef __TYPES_IDL__
  25. #include <Types.idl>
  26. #endif
  27. #if FOR_SYSTEM7_AND_SYSTEM8_DEPRECATED
  28. #ifndef __MIXEDMODE_IDL__
  29. #include <MixedMode.idl>
  30. #endif
  31. #endif
  32. #if FOR_SYSTEM8_PREEMPTIVE
  33. #ifndef __KERNEL_IDL__
  34. #include <Kernel.idl>
  35. #endif
  36. #ifndef __NAMEREGISTRY_IDL__
  37. #include <NameRegistry.idl>
  38. #endif
  39. #endif
  40.  
  41. #ifdef __SOMIDL__
  42.  
  43. #if FOR_SYSTEM8_PREEMPTIVE
  44. /*
  45. ========================================================================================
  46.  
  47.     The top of this file contains the Power Management interfaces used in Copland.
  48.     
  49.     The pre-Copland interfaces are below right after a large and obnoxious comment.
  50.  
  51. ========================================================================================
  52. */
  53. /*
  54. //************************************************************************************
  55.  
  56.     Low level (I/O architecture) interface
  57.     
  58. //************************************************************************************
  59. */
  60. /*
  61. //------------------------------------------------------------------------------------
  62.  
  63.     Power Management usage monitoring.
  64.  
  65.     High level families call PMMonitorUsage for each hardware device they maintain.
  66.     Power management will periodically send messages to the family requesting the
  67.     current UsageCount for each device.
  68.     If power management determines that a device is idle it may be taken off-line.
  69.     Prior to doing so power managment will send a message instructing the family to
  70.     prepare for the device being off-line. When the device is reqired again the family
  71.     uses PMPrepareDevice to instruct power management to bring the device back on-line.
  72.  
  73. //------------------------------------------------------------------------------------
  74. */
  75. typedef UInt32                    PMUsageCount;
  76.  
  77. typedef OpaquePtr                PMMonitorRef;
  78.  
  79. /*
  80. //------------------------------------------------------------------------------------
  81.  
  82.     Device Power State Management
  83.     
  84.     If a family maintains a device which is capable of switching between multiple
  85.     power states, the family should inform power management of the device's
  86.     capabilities and wait for messages directing it to change the device's power
  87.     state.
  88.  
  89. //------------------------------------------------------------------------------------
  90. */
  91. typedef OSType                    PMDeviceStateID;
  92.  
  93. typedef UInt32                    PMDeviceStateFlags;
  94.  
  95. typedef SOMLargeStruct            PMDeviceState;                /* Derived from a struct of 12 bytes in size */
  96.  
  97. typedef SOMLargeStruct            PMDeviceDescriptionHdr;        /* Derived from a struct of 8 bytes in size */
  98.  
  99. typedef SOMLargeStruct            PMDeviceDescription;        /* Derived from a struct of 32 bytes in size */
  100.  
  101. typedef OpaquePtr                PMManageRef;
  102.  
  103. /*
  104. //------------------------------------------------------------------------------------
  105.  
  106.     Power Management notification.
  107.     
  108.     Any entity in the I/O architecture can use these routines to be notified about
  109.     changes to device.
  110.     
  111.     Clients use a mask to specify which device aspects they are interested in and
  112.     also to specify when to be notified. Flags describing the new state are generated
  113.     and delivered with the notification.
  114.     
  115.     If the client is interested in power being removed and re-applied, they can request
  116.     it with (kPMNotifyAlwaysMask | kPMNotifyPowerMask). When the notification is 
  117.     delivered the client can check the new flags against kPMNotifyBeforeMask and
  118.     kPMNotifyAfterMask to determine if the change has already occured or not. And can
  119.     check against kPMDevicePoweredMask to determine if the device will have power or
  120.     not in the new state.
  121.     
  122. //------------------------------------------------------------------------------------
  123. */
  124. typedef UInt32                    PMNotifyFlags;
  125.  
  126. typedef OpaquePtr                PMNotifyRef;
  127.  
  128. /*
  129. //------------------------------------------------------------------------------------
  130.  
  131.     Power Management message
  132.     
  133.     This structure is used for all types of power management communication - usage
  134.     monitoring, state change notification, and state change commands.
  135.  
  136. //------------------------------------------------------------------------------------
  137. */
  138. typedef SOMLargeStruct            PMMessageData;                /* Derived from a struct of 8 bytes in size */
  139.  
  140. typedef SOMLargeStruct            PMMessage;                    /* Derived from a struct of 16 bytes in size */
  141.  
  142. /*
  143. //------------------------------------------------------------------------------------
  144.  
  145.     Restoring an off-line or powered off device to a usable state.
  146.     
  147.     When a device that has been taken off-line or has had its power removed is needed
  148.     again, the following routine should be called. This routine will return when after
  149.     the device has been restored (or has failed to be restored). Part of the restoration
  150.     process is delivering notifications to interested parties - kPMPowerRestore and/or
  151.     kPMPrepareOnLine messages will be delivered and processed before this routine 
  152.     returns.
  153.  
  154. //------------------------------------------------------------------------------------
  155. */
  156. /*
  157. //------------------------------------------------------------------------------------
  158.  
  159.     Disabling & Re-Enabling power managment of a device.
  160.     
  161.     Power management of a specific device can be disabled - this may be desirable
  162.     because of a resource reservation on some device. 
  163.     Families can implement a family specific API on top of this that can allow
  164.     an application to turn off power management for a particular volume or display
  165.     device.
  166.     
  167.     When power management of some device is disabled usage monitoring will still
  168.     occur, but there will not be any requests to change the device state. The
  169.     domain of which the device is a member will not be changed either.
  170.  
  171. //------------------------------------------------------------------------------------
  172. */
  173. /*
  174. //************************************************************************************
  175.  
  176.     Domain Controller Power Management Plug-In interface.
  177.  
  178. //************************************************************************************
  179. */
  180. /*
  181. //------------------------------------------------------------------------------------
  182.  
  183.     Domain description
  184.  
  185. //------------------------------------------------------------------------------------
  186. */
  187. typedef OSType                    PMDomainID;
  188.  
  189. typedef OSType                    PMDomainLevelID;
  190.  
  191. typedef UInt32                    PMDomainLevelFlags;
  192.  
  193. typedef SOMLargeStruct            PMDomainLevel;                /* Derived from a struct of 8 bytes in size */
  194.  
  195. typedef SOMLargeStruct            PMDomainDescriptionHdr;        /* Derived from a struct of 12 bytes in size */
  196.  
  197. typedef SOMLargeStruct            PMDomainDescription;        /* Derived from a struct of 28 bytes in size */
  198.  
  199. /*
  200. //------------------------------------------------------------------------------------
  201.  
  202.     Domain plugin. 
  203.     Plugin init routine returns pointer to a domain description as an out parameter.
  204.  
  205. //------------------------------------------------------------------------------------
  206. */
  207. typedef OpaquePtr PMDomainPluginInitProc;
  208. typedef OpaquePtr PMDomainPluginSetLevelProc;
  209. typedef SOMLargeStruct            PMDomainPluginDispatchTable; /* Derived from a struct of 24 bytes in size */
  210.  
  211. /*
  212. //************************************************************************************
  213.  
  214.     Platform plugin.
  215.     
  216. //************************************************************************************
  217. */
  218. typedef OpaquePtr PMSleepProc;
  219. typedef OpaquePtr PMHibernateProc;
  220. typedef OpaquePtr PMShutdownProc;
  221. typedef OpaquePtr PMRestartProc;
  222. typedef SOMLargeStruct            PMPlatformPlugin;            /* Derived from a struct of 32 bytes in size */
  223.  
  224. /*
  225. //************************************************************************************
  226.  
  227.     High level (application) interface.
  228.     
  229. //************************************************************************************
  230. */
  231. /*
  232.     Disk timer: the time a disk must be idle before it is spun down (or other
  233.     power management actions are taken). Applies to all disks, but each disk
  234.     has its own timer (one can stay spun up while the others are spun down).
  235.     
  236.     The minimum will be enforced.
  237.     
  238.     These API control system-wide parameters for the power management of disk devices.
  239.     For control over a specific disk see the <Block Storage or File System> API.
  240.     
  241.     
  242. */
  243. /*
  244.     Display timer: the period of time in which there has been no user input
  245.     before a display is dimmed or turned off. Applies to all displays, but
  246.     each display has its own timer.
  247.     
  248.     The minimum will be enforced.
  249. */
  250. /*
  251.     Idle state timer: the period of time in which all devices must be idle 
  252.     before the system is [?]. Basically, this is the timer for whatever action 
  253.     the user chose to happen when the system is idle. Could be sleep, hibernate,
  254.     or shutdown. If the user has explicitly disabled any action the    routines 
  255.     return an error.
  256.     
  257.     The minimum will be enforced and will be greater than or equal to the
  258.     maximum of disk spin down and display dimming times.
  259. */
  260. /*
  261.     Idle state: routines to get and set the action to be taken when power
  262.     management has determined that the system is idle.
  263.         Disabled: nothing happens when the machine is idle
  264.         Sleep is a soft definition - depends on the hardware: differs 
  265.         between portable and desktop systems.
  266.         Hibernate: save everthing and shutdown, on boot reload the saved
  267.         state.
  268.         Shutdown: just shutdown, nothing restored on boot.
  269. */
  270. /*
  271.     Misc. timers: These allow for programmable shutdown and power on. These are 
  272.     real absolute times - turn off at 6:00pm Jan 12 and back on at 8:00am Feb 1. 
  273.     The 'DateAndTimeSpec' is a made-up placeholder.
  274.     
  275.     Shutdown is a real shutdown.
  276.     IdleAction puts the machine into the chosen idle state - if the machine is
  277.     shutdown at the that time nothing happens.
  278.     PowerOn is either a normal boot or a return-from-idle depending on whether
  279.     the system is shutdown or is in its idle state.
  280. */
  281. /*    Immediate control over system state*/
  282. /*
  283. //------------------------------------------------------------------------------------
  284.  
  285.     Other high level API.
  286.     
  287.     Other families may want to implement their own power management API that is built
  288.     on top of the API presented here. Examples are the ability to turn off power
  289.     management of a specific storage volume or a specific graphics display. The battery
  290.     family will want/need to export a high level API that can show battery state.
  291.  
  292. //------------------------------------------------------------------------------------
  293. */
  294. /*
  295. //************************************************************************************
  296.  
  297.     User activity monitoring.
  298.     
  299.     These routine are used by software that is interested in the lack of and resumption
  300.     of user activity. The usage model is as follows: software requests to be notified
  301.     when all user activity has ceased for a specified amount of time. Once that
  302.     notification has been delivered any user activity will cause the second notification
  303.     to be delivered immediately. After delivery of the resume notification, the reference
  304.     is invalid and software must request notification again if it so desires.
  305.     
  306. //************************************************************************************
  307. */
  308. typedef OpaquePtr                PMUserMonitorRef;
  309.  
  310. #endif
  311. /*
  312. **************************************************************************************
  313.  
  314.  
  315.     Everything below this comment is the System 7.x Power Manager
  316.     
  317.     This comment is really large and obnoxious so that the separation can be easily
  318.     found when scrolling through the file.
  319.  
  320.  
  321. **************************************************************************************
  322. */
  323. #if FOR_SYSTEM7_AND_SYSTEM8_DEPRECATED
  324. /* bits in bitfield returned by PMFeatures */
  325. /* bits in bitfield returned by GetIntModemInfo and set by SetIntModemState */
  326. /* bits in BatteryInfo.flags                                     */
  327. /* ("chargerConnected" doesn't mean the charger is plugged in)    */
  328. /* client notification bits in PMgrQueueElement.pmNotifyBits */
  329. /* System Activity Selectors */
  330. /* Storage Media sleep mode defines */
  331. typedef SOMLargeStruct            ActivityInfo;                /* Derived from a struct of 6 bytes in size */
  332.  
  333. /* information returned by GetScaledBatteryInfo */
  334. typedef SOMFourByteStruct        BatteryInfo;                /* Derived from a struct of 4 bytes in size */
  335.  
  336. typedef SInt8                    ModemByte;
  337.  
  338. typedef SInt8                    BatteryByte;
  339.  
  340. typedef long                    PMResultCode;
  341.  
  342.  
  343.  
  344. typedef OpaquePtr                SleepQRecPtr;                /* Substituted OpaquePtr for ``SleepQRec*'' */
  345.  
  346.  
  347.  
  348.  
  349.  
  350. typedef OpaquePtr SleepQProcPtr;
  351. typedef OpaquePtr SleepQUPP;
  352. typedef OpaquePtr HDSpindownProcPtr;
  353. typedef OpaquePtr HDSpindownUPP;
  354. typedef OpaquePtr PMgrStateChangeProcPtr;
  355. typedef OpaquePtr PMgrStateChangeUPP;
  356. typedef SOMLargeStruct            SleepQRec;                    /* Derived from a struct of 12 bytes in size */
  357.  
  358. typedef SOMLargeStruct            HDQueueElement;                /* Derived from a struct of 16 bytes in size */
  359.  
  360. typedef SOMLargeStruct            PMgrQueueElement;            /* Derived from a struct of 20 bytes in size */
  361.  
  362. typedef SOMLargeStruct            BatteryTimeRec;                /* Derived from a struct of 16 bytes in size */
  363.  
  364. typedef SOMLargeStruct            WakeupTime;                    /* Derived from a struct of 6 bytes in size */
  365.  
  366. typedef SOMLargeStruct            StartupTime;                /* Derived from a struct of 6 bytes in size */
  367.  
  368. /* Public Power Management API (NEW!) */
  369. #endif
  370.  
  371. #endif /* __SOMIDL__ */
  372.  
  373. #endif /* __POWER_IDL__ */
  374.  
  375.